home *** CD-ROM | disk | FTP | other *** search
/ Atari Mega Archive 1 / Atari Mega Archive - Volume 1.iso / program / progem.arc / gem12.asc < prev    next >
Internet Message Format  |  1987-10-18  |  18KB
  1. From uwmcsd1!bbn!oberon!bloom-beacon!mit-eddie!rutgers!mcnc!ece-csc!ncrcae!ncr-sd!hp-sdd!hplabs!ucbvax!ucdavis!uop!exodus Sun Oct 18 08:32:23 CDT 1987
  2. Article 1989 of comp.sys.atari.st:
  3. Path: lakesys!uwmcsd1!bbn!oberon!bloom-beacon!mit-eddie!rutgers!mcnc!ece-csc!ncrcae!ncr-sd!hp-sdd!hplabs!ucbvax!ucdavis!uop!exodus
  4. >From: exodus@uop.UUCP (Freddy Kreuger)
  5. Newsgroups: comp.sys.atari.st
  6. Subject: Professional GEM Column #12
  7. Keywords: Tim Oren, ProGem
  8. Message-ID: <615@uop.UUCP>
  9. Date: 16 Oct 87 23:49:35 GMT
  10. Organization: Somewhere perpendicular to reality...
  11. Lines: 327
  12.  
  13.  
  14.                         *PROFESSIONAL GEM*
  15.                            By Tim Oren
  16.           Column #12:  GEM Events and Program Structure
  17.  
  18.      So I fibbed a little.  This issue (#12) of ST PRO GEM started
  19. out to be another discussion of interface issues.  But, as Tolkien
  20. once said, the tale grew in the telling, and this is now the first
  21. of  a series of three articles.   This part will discuss AES event
  22. handling  and  its implications for GEM  program  structure.   The
  23. following  article will contain a "home brew" dialog handler  with
  24. some  new  features,  and  the third will,  finally,  take up  the
  25. discussion  of  interface design,  using the dialog handler as  an
  26. example.   (There is no download for this article.   The downloads
  27. will return, with a vengeance, in ST PRO GEM #13.)
  28.  
  29.      ALL FOR ONE,  AND ONE FOR ALL.  A quick inspection of the AES
  30. documents  shows that there are five routines devoted  to  waiting
  31. for individual types of events, and one routine, evnt_multi, which
  32. is  used  when more than one type is desired.   This article  will
  33. discuss  ONLY evnt_multi for two reasons.   First,  it is the most
  34. frequently used of the routines.   Second, waiting for one type of
  35. event is a bad practice.   Any event call turns the system over to
  36. the AES and suspends the application and its interaction with  the
  37. user.   In  such  cases,  some  "escape clause",  such as a timer,
  38. should be inserted to revive the program and prompt the user if no
  39. event  is  forthcoming.   Otherwise,  the  application may end  up
  40. apparently  (or  actually)  hung,  with a  resulting  reboot,  and
  41. probably a very annoyed user.
  42.  
  43.      STARTING  AHEAD.   One  possible type of event is a  message.
  44. Messages  are usually sent to the application by the AES,  and are
  45. associated  with  windows or the menu.   Two previous articles  in
  46. this  series have discussed such messages.   ST PRO GEM number two
  47. considered   window  messages,   and  number  seven  handled  menu
  48. messages.  You may want to review these topics before proceeding.
  49.  
  50.      The actual evnt_multi call is a horrendous thing:
  51.  
  52.      ev_which = evnt_multi(ev_flags,
  53.                btn_clicks, btn_mask, btn_state,
  54.                r1_flags, r1_x, r1_y, r1_w, r1_h,
  55.                r2_flags, r2_x, r2_y, r2_w, r2_h,
  56.                &msg_buff,
  57.                time_lo, time_hi,
  58.                &mx, &my, &btn, &kbd, &char, &clicks);
  59.  
  60. Each  of  the lines in the call relate to a different  event,  and
  61. they  will be discussed in the order in which they  appear.
  62.  
  63.      Note  that a call with this number of parameters causes  some
  64. overhead  due  to stacking and retrieval of the values.   In  most
  65. cases,  this  should be of little concern on a machine as fast  as
  66. the ST.   However, where throughput is a concern, such as in close
  67. tracking  of the mouse cursor,  you may want to write a customized
  68. binding  for evnt_multi which dispenses with the  parameter  list.
  69. This  can  be accomplished by maintaining the values in  a  static
  70. array  and moving them as a block into the binding  arrays  int_in
  71. (for all values but &msg_buff), and addr_in (for &msg_buff).  Note
  72. that  you  may NOT simply leave the values in  int_in;  other  AES
  73. bindings reuse this space.
  74.  
  75.      Ev_flags  and ev_which are both 16-bit integers  composed  of
  76. flag bits.  Bits set in ev_flags determine which event(s) the call
  77. will  wait  for;  those  set in ev_which  indicate  what  event(s)
  78. actually occurred.   Both use the following flag bit mnemonics and
  79. functions:
  80.  
  81.      0x0001 - MU_KEYBD - Keyboard input
  82.      0x0002 - MU_BUTTON - Mouse button(s)
  83.      0x0004 - MU_M1 - Mouse rectangle #1
  84.      0x0008 - MU_M2 - Mouse rectangle #2
  85.      0x0010 - MU_MESAG - AES message
  86.      0x0020 - MU_TIMER - Timer
  87.  
  88. The  appropriate mnemonics are ORed together to create the  proper
  89. ev_flags value.
  90.  
  91.      There  is  one  common pitfall here.   Notice  that  multiple
  92. events  may  be reported from one evnt_multi.   Event  merging  is
  93. performed  by the AES in order to save space on the  application's
  94. event queue.   If events have been merged,  more than one bit will
  95. be  set in the ev_which word.   Your application must check ALL of
  96. the  bits  before  returning to a new  evnt_multi  call.   If  you
  97. don't do this, some events may be effectively lost.
  98.  
  99.      The  first event to be considered is the mouse button.   This
  100. is probably the most difficult event to understand and use, and it
  101. has one major shortcoming.
  102.  
  103.      The  parameter  btn_clicks tells GEM the  maximum  number  of
  104. clicks which you are interested in seeing.   This value is usually
  105. two,  if your program uses the double-click method, or one if only
  106. single  clicks  are used.   The AES returns the number  of  clicks
  107. which caused the event through &clicks, which must be a pointer to
  108. a word.
  109.  
  110.      GEM determines the number of clicks by the following  method.
  111. When the first button-down is detected, a time delay is begun.  If
  112. another  complete button-up,  button-down cycle is detected before
  113. the time expires,  then the result is a double click.   Otherwise,
  114. the  event is a single click.    Note that the final state of  the
  115. buttons  is  returned via &btn,  as described below.   By checking
  116. this  final state,  you may determine whether a single click event
  117. ended with the button up (a full click),  or with the button still
  118. down  (which  may  be  interpreted as  the  beginning  of  a  drag
  119. operation).   Double clicking is meaningless,  and not checked, if
  120. the evnt_multi is waiting on more than one button (see below).
  121.  
  122.      The double-click detection delay is variable,  and may be set
  123. by your program using the call
  124.  
  125.      ev_dspeed = ev_dclick(ev_dnew, ev_dfunc);
  126.  
  127. Ev_dfunc  is a flag which determines the purpose of the call.   If
  128. it  is  zero,  the  current  double click  speed  is  returned  in
  129. ev_dspeed.   If ev_dfunc is non-zero, then ev_dnew becomes the new
  130. double-click   speed.    Both  ev_dspeed  and  ev_dnew  are  words
  131. containing  a "magic number" between zero and four.   Zero is  the
  132. slowest  (i.e.,  longest)  double-click,  and four is the fastest.
  133. (These  correspond  to  the  slow-fast  range  in  the   Desktop's
  134. Preferences  dialog.)  In general,  you should not reset the click
  135. speed  unless  specifically requested,  because such a change  can
  136. throw off the user's timing and destroy the hand/eye  coordination
  137. involved in using the mouse.
  138.  
  139.      GEM  was  originally designed to work with  a  single  button
  140. input device.   This allows GEM applications to function well with
  141. devices such as light pens and digitizing tablets.   However, some
  142. features are available for dealing with multi-button mice like the
  143. ST's.
  144.  
  145.      The  evnt_multi parameters btn_mask and btn_state  are  words
  146. containing  flag bits corresponding to buttons.   The lowest order
  147. bit corresponds to the left-most button,  and so on.  A bit is set
  148. in  the  btn_mask parameter if the AES is to  watch  a  particular
  149. button.   The  corresponding bit in btn_state is set to the  value
  150. for  which  the program is waiting.   The word returned  via  &btn
  151. uses  the  same  bit system to show the state of  the  buttons  at
  152. completion.   It  is  important to notice that all of  the  target
  153. states in btn_state must occur SIMULTANEOUSLY for the event to  be
  154. triggered.
  155.  
  156.      Note the limiting nature of this last statement.  It prevents
  157. a  program from waiting for EITHER the left or right button to  be
  158. pressed.  Instead, it must wait for BOTH to be pressed, which is a
  159. difficult  operation  at best.   As a result,  the standard  mouse
  160. button  procedure is practically useless if you want to take  full
  161. advantage  of  both buttons on the ST mouse.